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INTRODUCTION 


SORTIT is an 8080 assembly lancuace Procram that Provides efficient 
sortine of seauentiasl datafiles usinc the Hearsort agleorithm. The rrocram 
interfaces North Star DOS for disk and user communication. SORTIT is 
Provided in two versions for execution at 2600H-.or ZDOOH. Both versions 
handle sinsle/double densitu» sincle/double sided drives. The datafile 
must meet North Star BASIC datafile definitions. 


With SORTIT, records may he deleted based on a comparison with a delete 
key. Records may be sorted in ascending or descending order based on a 
erimaru keu and ortionallu»s a secondary key. Both keys may be numeric or 
one to nine character strines with the string in 3 defined field rosition 
or richt-Justified. 


SORTIT requires a detailed definition of the format of the datafile to be 
sorted. After a user defined descrirtion is entered» it may be saved py 
writing the SORTIT procram to disk under a new Frocram name. SORTIT is 
released with two Predefined file descrirtions for use with datafiles 
Generated by the DYNACOMF MAILLIST II prosrams sortirs on name or on zip 
code. 


For single drive systems» the source datafile and destination datafile 
must reside on the same disk. For multirle drive systems each of tne two 
datefiles may exist on any of the drives.  SORTIT does NOT write to or 
update the source datafile. 


The CUSTOMIZING SORTIT section of tnis manual describes the various 
chances that may be made by the user to conficure the rrocram to a 
particular systems. 


Memory reauirements are determined by the datafile size. See MEMORY 
REQUIREMENTS section for details. 


The following is a brief descrirtion of SORTIT oreration with emrhasis or 
defining the terminolocy used in this manual. 


The source datafile and sorted destination datafile are identified by one 
to eight character filenames followed by a comma and the disk drive 
number. The datafiles are defined to the North Star EASIC reauirements. 
North Star BASIC allows numeric precision of 6» 8» 10» 12 or 14 dicits» 
with 8 - dicit precision as standard. The SORTIT customizing table must 
specify the precision in use. 


A SORTIT datafile consists of an ortional master record followed by one or 
more fixed format data records followed by an endmarker . 


The master record if Present is simrlw copied to the destination file. It 
must be defined in the file description as to the number of fields in the 
record. 


The data records are also defined in the file descrirtior. They must all 
be of the same format; that is» the same number of fields and field tyres. 
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Each data record must contain all defined fields unless an earlier 
numeric field is rresent that contains the value of the total number of 
fields, 


Data records may be of variable leneth in the sense that string fields are 
of variable leneth and also in the sense that a srecific record may have 
less than the maximum defined number of fields if s variable field count 
value is provided. For advanced users: a special fixed length definition 
is described in a later section of this manual. 


SORTIT execution is locicalls divided into four Phases, The initialization 
Phase will display the current file definition and accept a new file 
definitions then request source and destination filenames. The array 
build phase reads the source file seauentially and builds a 23 byte entry 
in system memory for each data record to be sorted. The hearsort rhase 
then sorts these array entries in system memory into the desired order. 
The cory Phase uses the order of the array entries to read each data 
record from the source file and write it to the destination file, 


During the initialization rhases SORTIT disrlaws the current file 
definition and requests a new file definiton and source/destination 
filenames thru the use of the followinc rromrt lines. The Promet line 
numbers on tne left side of the list are added here for the purpose of 
easy referencing im later sections of this manual and do not arrear with 
the line on the CRT display. A few of the more obvious rromrts are not 
included in this list. 


- MASTER - + OF FIELDS = 

- DATA RECORD ~ + OF FIELDS = 

- FIELD # OF VARIABLE FIELD COUNT = 

- VARIABLE + OF FIELDS OFFSET = 

FIELD # OF DELETE KEY (STRING TYFE ONLY) = 
- LENGTH OF KEY (0 TO 9 ONLY) = 

- OFFSET TO START OF KEY = 

- ENTER DELETE KEY - 1 TO $ CHARS 3 

- FIELD # OF FRIMARY KEY = 

10 - FIELD TYFE - NUMERIC OR STRING ? N/S3 
11 - LENGTH OF KEY (0 TO 9 ONLY) = 

12 - OFFSET TO START OF KEY = 

13 - FIELD + OF SECONDARY KEY = 

14 - FIELD TYOE - NUMERIC OR STRING ? N/S3 
15 - LENGTH OF KEY (0 TO 9 ONLY) = 

16 - OFFSET TO START OF KEY = 

17 - ASCENDING/DESCENDING SORT ? A/D} 
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If SORTIT is to be used to rerlace the internal sort of MAILLIST» the 
reader is advised to study the first three sections of this manual. Users 
who wish to sort other datefiles should study the entire manual prior to 
attempting to use SORTIT., The master disk supplied by DYNACOMF should be 
write protected and used only to cory the rrocram onto 2 working disk. 


The entry of a control-c durina the execution of SORTIT has two Possible 
results. If SORTIT has issued a Promet messace and is accertira keyboard 
imruty tne entry of a control-c anytime ur to the entry of a 

carrisce-return will result in an immediate rrocram abort and Jum» to the 


DOS reentry address. 


Entry of a control-c during the array build phases sort rhases or cory 
Phase will result in a status message display that will contain a relative 
Processing ٣اا‎ ٤٢ | 


The record number displayed in the status messace is only a relative value 
to allow the user to verify that rrocessing is continuing. SORTIT will 
await the entry of a carrisce return to continues 


The record numbers disrlaued at the final status rerort are true record 
totals. 


CUSTOMIZING SORTIT 


The following table lists the various assignments of the first 42 bytes of 
SORTIT with a comment on the use of each assignment. Modifying these 
values can result in a customized Pprocrame Note that all values are in 
hex. The values shown are Provided in the master cory of the Procram. 

The location value is for the 2A00H version and has the same relative 
offsets at 2D00H for the other version. 


Location Label Value Comment 

ZA00 START C3 XX XX JUMF TO FROGRÁM START 
2A03 DOUT C3 0D 20 TO DOS TERMINAL OUTFUT 
26506 DINF C3 1020 | TO DOS KEYEOARD INFUT 
20609 CLEAR C9 00 00 TO USER SCREEN CLEAR 
260 DCOM C3 22 20 TO DOS DISK COMMAND 

260 DLOOK C3 1C 20 TO DOS DIRECTORY SEARCH 
2512 DOS C3 28 Z TO DOS REENTRY 

ZALS CONTC C3 16 20 TO DOS STATUS CHECK 
26518 RUEO SF INFUT DELETE CHARACTER 
2A19 ECHOR SF ECHOED DELETE CHARACTER 
26516 OFORT 00 OUTFUT FORT ۴ 

ZALE IFORT 00 INFUT FORT 4 

ZAIC MSIZE 00 00 MASTER KECORD FIXED SIZE 
2A1E DSIZE 00 00 ` DATA RECORD FIXED SIZE 
265020 MEMEND FF SF END OF MEMORY 

26 PRECISION 05 NUMERIC FRECISION 

26523 SKIFD 00 SKIF DISFLAY FLAG 

20624 SKIFQ 00 SKIF FILE DEFINITION REQUEST 
26029 SKIFF 00 SKIF FILENAME KEYIN 
2626 CASEF 00 SKIF CASE CONVERSION 
26027 SFARE (3 BYTES) FUTURE USE 

















4 


The Start entry is the execution entry Point (rot 3 subroutine call). The 
next seven entries are all called from within SORTIT. See the North Star 
DOS descrirtions for the reauired interface reauirements. The Clear entry 
is set to an immediate return. If the user rrovides the address of a 
clear screen routine at this roint» it will be called during SORTIT 
initialization. 


Rubo and/or Echor may be changed if the user's terminal requires different 
delete characters, | 


Msize and Dsize are described in a later section of this manual (FIXED 
LENGTH RECORDS). 


Memend should be set (low order/hich order butes) to the hichest available 
conticuous memor«v address above ZA00H. 


Frecision is set to reflect the standard version of North Star BASIC or 


custom versions for different numeric rrecisions, Standard 8 - dicit 
Precision is set by a value of 5. ó - dicit precision -4; 10 - dicit 
Precision = 63 12 - digit Precision = 73 14 - dicit Precision = 8, 


Non-standard precisions must be matched with the arpprorriste custom 
version of BASIC. 


5kimrd» if set non-zero will result in SORTIT skirrinc the orening ‘Display 
File Definition' request. 


Skira» if seti non-zero will result in SORTIT skirrins the 'Define New 
File' request, 


Skirfs if set non-zero will result in SORTIT skirrinc the 
source/destination filenames reauests. 


Casefy if set non-zero will remove the conversion of lowercase letters to 
uppercase 0۱۱۳ 1۳۱6 Primary and secondary key comrarisors, 


MAILLIST II SORTING 


The 2A00H version of SORTIT on the master disk has been preset to Provide 
an alrnabetic ascending sort on the name field of a MAILLIST file. If 
executed as is» ili will rrovide the user with a very fast sort. The 2D00H 
version is preset for an ascending zir code sort. Both versions will 
delete the @rrrorriately marked records, 


You may create a 2A00H version of the zir code sort by first executing the 
ZD00H version and displaying the file definition. Record the values 
disrlased and cancel the 2D00H version by entering 2a control-c. Now» 

۲۲ 6۳6۲۵ a new rProacram area or your working disk for a rew cory of SORTIT. 
Execute the 2A00H version and resrond 'Y' to the define file rromrt. 
Resrond to eacn file promet with the corresronding value you earlier 
recorded from the 2D00H version. After all rromrts have been answered, 
resrond 'Y' to the ‘save this file definition’ Promrt and use the DOS save 
file (SF) command to save this version under sour new rrocram name. You 
now have a ZA00H version for zir sort. 


A similar techniaue mas be used to obtain a 2D00H version of an alrha 
sort. 




















5 


The MAILLIST II user may wish to enhance his sort carability with SORTIT 
versions that rrovide? 


Descendincac sorts. 

Delete key ProcessinGo. 

1l to 9 character Primary key sorts. 

1 to 9 character secondary key sorts. 


A full study of this manual should Provide the knowledce needed to enhance 
the MAILLIST sort in many ways. 


MEMORY REQUIREMENTS 


SORTIT reauires contiguous memory for rProacram» I/O buffers and hearsort 
array. The available memory for the hearsort array will determine the 
larcest file size that may be sorted. The following table shows the 
address of tne start of the hearsort array derendins on SORTIT version and 
on the density of the two datafiles. 


ZAOOH Version 2DO0H Version 
Eoth datsafiles sinsle density! 4100H 4400H 
One datafile double density? 4200H 4500H 
Eoth datafiles double density? 4300H 460 01 


Once the user has obtained the hearsort arrau start address from the above 
tables subtract this value from the MEMEND value in the customizing table 
to obtain the available memory for the hearsort array. Dividine this size 
(expressed im decimal) by 23 decimal will result in the maximum number of 
data records that may be sorted, The following is an examrle. 


For a 2D00H version with both datafiles of single density, hearsort array 
start address is 4400H. If MEMEND is set at 63FFH» then available sort 
memory is 1FFFHy» which is 8191 decimal. 8191 divided by 23 results in 356 
as the number of data records that may be sorted with this memory size. 


Note that if a source datafile has data records thet will be deleted due 
to the use of the delete key definitions these records are not included in 
the above maximum number of sort records. 


MASTER RECORD PROCESSING 


Some datafiles are built with the first record of the file containinc 
overall file parameters. This initial record (referred to as the master 
record) may have a different format than the following date records. 


If the resronse to the master number of fields prompt (line + 1) is zero» 
then SORTIT will not exrect the existence of a master record. If the 
resronse is 1 to 255, then SORTIT will cory a master record from the 
source to tne destination file as the first record on the file and it will 
contain the defined number of fields. 


DATA RECORD PROCESSING 
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The data records may contain from 1 to 255 fields (the number srecified by 
response to rromrt line # 2) with all records containinc the same number 
of fields (for excertions see below). The fields may be North Star EASIC 
numeric fields» string fields of 1 to 255 characters or lone strine fields 
of 256 or more characters. Each data record must be of the same field 
format. For examrle» if the third field of one record is numeric then the 
third field of all data records must be numeric. The strinc field of less 
than 256 characters in one record may corresrond to asa lonc strinc field in 
other data records» however there are some restrictions on the use of lone 
strina fields, described later» that must be considered. 


DELETE KEY PROCESSING 


A useful feature of SORTIT is the ability to delete records (that is» NOT 
COPY a record to the destination file) that contain e match with a user 
defined delete key, 


The delete key may not be a numeric field and the 1 to 9 character strine 
is entered in the file definition on resronse to promet line € 8 with the 
length of the key in resronse to rromet line # 6. The ares of each data 
record that is tested for a match is defined by srecifyineg a field number 
(see rromrt line # $5) of other than zero and a key offset value. If the 
key is left-Justified in the field then the offset value should be set to 
1 (see rPromrt line * 7). If the keu is richt-Justified in 3 strings or 
right Justified in the first 255 rositions of a lone strine field», then 
the offset value should be set to zero. If the rosition is fixed within 
the first 255 buies of tne field» then the offset value should be set to 
the position of the start of the key area. For examrles» if the field is 
300 bytes and the fifteenth thru the twenty-first characters are the 
desired delete keys» then offset should be set to 15 and lencth should be 
set to 7. 


Note that the delete key area must always be within the first 255 
characters of the field. Each character in the key area is compared to 
the delete key corresrondinae rosition and for deletion the characters must 
match exactly. Urrercase characters will not match with lowercase 
characters. There is ar excertions if the character in the defined delete 
key is a question mark (ASCII 3FH)s, then any character in the 
corresrondinc data record area will be considered 3 match, Note that a 
defined delete key consisting of all auestion marks would result in 
deleting every record that contained a field of sufficient lencth to have 
at least all the srecified delete key lencth. ۱ 


FRIMARY AND SECONDARY KEY FROCESSING 


The primary and secondary kews are defined in the same way and have the 
same characteristics. A Primary key field number must always be srecified 
(see Promet line + 9) but a secondary key need not be srecified (resronse 
to Promet line # 13 of zero). The rest of this section will refer to 
either key, 


The key field may be mumeric or string. If numeric» an ascending sort 
will select the most necative values» then zero» then Positive values 
usinc 8 dicit rrecision or ortionally one of the non-standard Precision 
values. Descending sorts will reverse the above order. 
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If the kes field is a strine ture the definition and record area useage is 
the same as described for the delete key excert that all lowercase letters 
are converted to urrercase letters for the comparison testing and there is 
no use of the auestion mark delimiter. The customizing section describes 
how to disable the lowercase to urrercase conversions if desired, 


If the record lencth is not sufficient to contain the full number of 
characters defined bu the kes lencth» then the reduced number of 
characters will be used. If the field is so short as to contain no 
characters to use for sortinc» this record uill arrear at the front of the 
sorted file on ascendina sorts» or at the end of the sorted file on 
descending sorts. 


VARIABLE FIELD COUNT PROCESSING 


Some procrams that build datafiles use the techniaue of Providing s field 
counter value in one of the first fields of each data record, The data 
records are defined to contain a certain minimum number of fields and a 
certain maximum number of fields. The field counter value in each data 
record defines the total number of fields Present for that rFarticular 
record. 


SORTIT will Process this ture of datafile bs allowing the definition of a 
'variable field count' and a variable offset value. The maximum number of 
fields in a data record is specified in the resronse to tne number of 
fields prompt (line # 2). The location of the numeric field to be used 
for the variable field counter is used in resronse to the 'field number of 
variable field count' (rromrPt line + 3). If» for examrle» the second 
field of each record is a numeric field containing a value equal to the 
number of remaining fields in the record» then resronse to prompt line # 3 
would be 2, The actual value contained in this second field would be zero 
if no additional fields were in this Particular record. SORTIT reauires 
an offset value to be defined that when added to the value contained irn 
the variable count field will result in the total number of fields 
Present. For the above examrle» the resronse to the offset promet (line # 
4) should be 2. If the data record contains four fields» the contents of 
the second field (2) will be added to the offset (2) to obtain the total 
number of fields (4). 


As another examrles the MAILLIST datafile contains variable field size 
records from 5 to 7 fields» with a variable field count value from 3 to 5 
in the first field of each data record. Resronse to the number of fields 
eromet (line 4 2) is 75 to the field number of the variable count prompt 
(line # 3) is 13 and to the field count offset prompt (line + 4) is Ze 


The optional master record does not use this variable field counts» the 
record must contain the exact number of fields srecified in resronse to 
promrt line # 1, 


The variable field count field must be of numeric iure. 


If the file is of this variable count tyre and any of the key definitions 
are specified as richt-Justified» then the key will be obtained from its 
defined field number -OR- from the last field in the record if there are 
less fields in the record than the defined field number. In other words» 
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the key area is richt-Justified in the field -AND- irn the record» if the 
record is sufficiently short. 


FIXED LENGTH RECORDS 


The Previous sections have described the data records as if they were Part 
of a true sequential files with each record immediately following another. 
Some access methods Place data records at fixed leneth blocks in the 
datafile. If a rarticular record is smaller than the assicned spacer an 
unused number of bytes occur between the record and the next record in the 
file. 


For this tyre of 'random access' file techniaue,; SORTIT mas be customized 
to recosnize and advance to the next record by sterring Past the unused 
bytes. 


The user must set the MSIZE value (low order byte first) in the 
customizing table to the total fixed lencth for the master record» if 
Present. For the data records the user must set the DSIZE value Clow 
order bute first) in the customizinc table. All other asrects of the data 
records continue to be as described throughout this manual including the 
variable field count carsbilities. Of course»; the record must never 
exceed the fixed lencth value. The datafile endmarker (01H) must occur on 
a fixed record boundary and not immediately following the last byte of the 
last field. 


ERROR PROCESSING 


Durina file srecification» the entry of an undefined or out of range value 
will result im the immediate rereat of the same Promet line. For examrle» 
entry of a 12 to a length promet (key lenaths are 1 to 9) will result in 
the same rromrt being rerested. 


If both datafiles are or the same drive at the same location (maybe the 
same filename)» SORTIT will rereat the filenames PrOMP LS» 


If a file is not rresent on the srecified drive» SORTIT will outrut the 
messace '-filename- NOT FOUND ON DRIVE, RETRY? Y/N'. If you then 
rrorerly load the drive and resrond ‘Y's SORTIT will continue. Amy other 
resronse will cause ar abort and reentry to DOS. 


If» after the initial check and during later rFrocessinc» a file is not 
found on the srecified drive the messace 'DISK FILE NO LONGER AUAILABLE! 
is disrlaued and SORTIT will reenter DOS. 


If during rrocessinss a field is found of a different ture than exrected: 
SORTIT will disrlay 'UNKNOWN RECORD TYFE DETECTED' and will reenter DOS. 


If the datafile contains a Greater number of records than mau be rrocessed 
in the Hearsort array memory areas SORTIT will disrlaws 'SORRY» 
INSUFFICIENT MEMORY' and will reenter DOS. 


If SORTIT does not recognize an endmarker im the source datafiler or 
cannot fit all of the records in the destination datafile, the 'DISK FILE 
SIZE PROELEM' messace will be disrlayed and DOS will be reentered. 


The final status rerort disPlased by SORTIT indicates the total records 
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coried (includinc the master record» if Frresent); the number of records 
deleted due to match on the delete kes? the number of bad rrimasries and 
number of bad secondaries, A had rrimarwu/secondars occurs when the field 
ture does not match the srecified tyre. These records will be moved to 
the sorted file and the total records coried reflects this move. They 
Will be at the front of the file om ascending sorts and at the back on 
descending sorts. 
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